home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / tosfixes / fser096b.lzh / FSER096B / XSDD.TXT < prev   
Text File  |  1992-09-12  |  19KB  |  441 lines
  1. Extended Serial Device Driver (XSDD)
  2.  
  3. Entwurf eines Protokolls mit erweiterten Funktionen zur seriellen I/O
  4.  
  5. Author: Stephan Baucke
  6. Erste Niederschrift: 7-Sept-1992
  7. Letzte Änderung: 11-Sept-1992
  8.  
  9. Einleitung
  10. ----------
  11.  
  12. Bekanntlich sind die Möglichkeiten des TOS zur Bedienung der seriellen Schnitt-
  13. stellen recht beschränkt:
  14.  
  15. - die Bedienung diverser Kontrolleitungen (wie DCD, DTR, RI usw.) ist nur durch
  16.   Direktzugriff auf die Hardware möglich
  17. - Es sind nur die von Rsconf angebotenen Baudraten einstellbar, auch wenn die
  18.   Hardware mehr erlaubt
  19. - Der Zugriff auf eine Schnittstelle von mehreren Programmen kann nicht koordiniert
  20.   werden
  21. - Da mit BIOS jedes Zeichen einzeln übertragen werden muß, ist die I/O-Performance
  22.   nicht sehr hoch
  23.  
  24. Im Rahmen der Entwicklung eines seriellen Treibers für MiNT, der diese Schwächen
  25. beheben sollte, kam die Idee auf, die erweiterte Funktionalität auch unter reinem
  26. TOS zugänglich zu machen. Dies ist ein erster Vorschlag, wie das aussehen könnte.
  27. Im wesentlichen werden dabei die Low-Level-Routinen des MiNT-Treibers über einen
  28. Cookie von außen zugänglich gemacht. Denkbar wäre jedoch auch, die beiden Ebenen
  29. völlig zu trennen und den MiNT-Treiber auf einen separaten TOS-Treiber aufzu-
  30. setzen.
  31.  
  32.  
  33. Das XSDD-Protokoll
  34. ------------------
  35.  
  36. Das XSDD-Protokoll unterstützt die über Bconmap verwalteten Devices 6 bis ein-
  37. schließlich <maptabsize+5> (soweit das zugrundeliegende TOS sie zur Verfügung
  38. stellt), sowie das Device 1 (AUX). Operationen auf AUX beziehen sich immer auf
  39. das zum Zeitpunkt des Aufrufs von XSDD gerade aktuelle Bconmap-Device. In Zu-
  40. kunft wird AUX möglicherweise aus technischen Gründen nur noch dann unterstützt,
  41. wenn das zugrundeliegende TOS kein Bconmap hat.
  42.  
  43. Der Treiber installiert einen Cookie "XSDD". Der Cookie zeigt auf den Einsprung-
  44. punkt des XSDD-Treibers. Unmittelbar vor der Routine (also an Offset -4 vor der
  45. Adresse aus dem Cookie) steht zur Absicherung nochmals die Long-Konstante "XSDD".
  46.  
  47. Aufruf: Welche Funktion ausgeführt werden soll, wird durch einen Opcode (WORD)
  48. angegeben. Dieser Opcode ist bei jedem Aufruf das erste Argument. Wenn ein un-
  49. gültiger Opcode angegeben wird, wird EINVFN zurückgeliefert.
  50.  
  51. Die Übergabe aller Parameter erfolgt nach GEMDOS-Konvention, d.h. auf dem Stack.
  52. Der Rückgabewert wird in D0 geliefert. Außer D0 werden keine Register verändert.
  53. Der Aufruf von XSDD darf AUSSCHLIESSLICH im Supervisor-Modus erfolgen. 
  54.  
  55. Z.Zt. sind die im folgenden aufgelisteten Funktionen vorgesehen (Opcodes müssen
  56. noch vergeben werden). Für die Parametertypen gilt folgende Vereinbarung:
  57.  
  58. BYTE:  8-Bit-Zeichen
  59. WORD:  16-Bit signed Integer
  60. UWORD: 16-Bit unsigned Integer
  61. LONG:  32-Bit signed Integer
  62.  
  63. -----------------------------------------------------------------------------------
  64. WORD XSVersion(void)
  65.   Liefert die Versionsnummer des vom XSDD-Treibers implementierten Protokolls
  66.   zurück, Major-Version im Hi-Byte, Minor-Version im Low-Byte (Beispiel: 0x0102
  67.   entspricht Version 1.2). Diese Nummer soll nicht etwa die Version des Treiber-
  68.   programms wiederspiegeln, sondern nur die des implementierten Protokolls.
  69.  
  70.   Rückgabe:
  71.   Protokollversion.
  72.  
  73. -----------------------------------------------------------------------------------
  74. WORD XSDriverInfo(BYTE *info, LONG *product, WORD *version)
  75.   Dieser Aufruf liefert einen Info-String, eine Produktkennung, sowie die Version
  76.   des jeweiligen Treiberprogramms zurück. `info' muß dabei auf einen mindestens 80
  77.   Bytes großen Puffer zeigen, in den der Info-String nullterminiert eingetragen
  78.   wird (der String kann z.B. den Author und den Namen des Treibers enthalten). In
  79.   den LONG, auf den `product' zeigt, wird die Produktkennung eingetragen, sowie in
  80.   das WORD, auf das `version' zeigt, die Treiberversion.
  81.   
  82.   Rückgabe
  83.   0
  84.  
  85. -----------------------------------------------------------------------------------
  86. WORD XSDevName(WORD device, BYTE *name)
  87.   Ermittelt den Namen des zum BIOS-Device gehörigen Ports (z.B. "Modem1"). `name'
  88.   muß auf ein mindestens 9 Bytes großes Array zeigen. Dort wird der Name nulltermi-
  89.   niert eingetragen.
  90.   
  91.   Rückgabe:
  92.   0 bei Erfolg
  93.   EUNDEV - Ungültiges Device
  94.  
  95. -----------------------------------------------------------------------------------
  96. WORD XSReserve(WORD device)
  97.   Device reservieren. Es handelt sich hier um ein "advisory" Locking, d.h. es ist
  98.   darauf angewiesen, daß jedes Programm den Lock abfragt und freiwillig auf weitere
  99.   Zugriffe verzichtet, wenn das Device bereits belegt ist. Jedes Programm hat vor
  100.   irgendeinem Zugriff auf das Device diesen Aufruf durchzuführen. Wenn das Device
  101.   noch frei  war, ist es nach dem Aufruf reserviert. Wenn es bereits reserviert war,
  102.   wird ein Fehlercode zurückgeliefert. In diesem Fall sollte keinerlei Zugriff mehr
  103.   auf das Device erfolgen.
  104.   
  105.   Rückgabewert:
  106.   0 - das Device ist jetzt reserviert
  107.   EACCDN - das Gerät war bereits reserviert
  108.   EUNDEV - Ungültiges Device
  109.  
  110. -----------------------------------------------------------------------------------
  111. WORD XSRelease(WORD device)
  112.   Device wieder freigeben. Dieser Aufruf darf NUR gemacht werden, wenn vorher
  113.   ein erfolgreicher XSReserve durchgeführt werden konnte (mit Rückgabe 0).
  114.  
  115.   Falls auf dem Device noch eine XSCtlSig-Routine angemeldet war, wird sie
  116.   automatisch freigegeben.
  117.  
  118.   Rückgabewert:
  119.   0 bei Erfolg, 
  120.   EACCDN - wenn das Device nicht reserviert war.
  121.   EUNDEV - Ungültiges Device
  122.  
  123. -----------------------------------------------------------------------------------
  124. LONG XSCapMap(WORD device)
  125.   Fragt diverse Eigenschaften von Treiber und Device ab. Wenn kein Fehler vorliegt,
  126.   wird ein Bitvektor zurückgeliefert. Folgende Bits sind z.Zt. definiert:
  127.  
  128.   #define XS_BREAK    0x01   /* Device kann Break senden */
  129.   #define XS_RTSCTS 0x02   /* Device beherrscht RTS/CTS-Handshaking */
  130.   #define XS_TANDEM 0x04   /* Device beherrscht XON/XOFF-Handshaking */  
  131.   #define XS_IOBAUD 0x08   /* Device beherrscht verschiedene I- und O-Baudraten */
  132.  
  133.   #define XS_BIOSRW 0x8000 /* Treiber benutzt BIOS zum Lesen/Schreiben */
  134.   
  135.   Alle anderen Bits sind reserviert und sollten bis auf weiteres ignoriert
  136.   werden.
  137.   
  138.   Rückgabewert:
  139.   >=0 (LONG!) - Verfügbare Fähigkeiten
  140.   EUNDEV - Ungültiges Device
  141.  
  142. -----------------------------------------------------------------------------------
  143. LONG XSIBaud(WORD device, LONG baudrate)
  144.   Eingabe-Baudrate (genauer: bps) des angegebenen Devices setzen/abfragen. Die Baud-
  145.   rate wird unkodiert im "Klartext" angegeben (38400L entspricht z.B. 38400 bps).
  146.   Wenn -1L angegeben wird, wird die Baudrate nicht verändert (nur Abfrage). Falls
  147.   eine Baudrate angfordert wird, die auf dem Device nicht zur Verfügung steht, wird
  148.   die nächst niedrigere verfügbare eingestellt und zurückgeliefert.
  149.  
  150.   Die meisten Devices unterstützen keine getrennten Baudraten für Ein- und Aus-
  151.   gabe. In diesem Fall wird mit einem XSIBaud gleichzeitig auch die Ausgabe-
  152.   Baudrate verändert (dies kann mit XSCapMap abgefragt werden).
  153.  
  154.   Rückgabewert:
  155.   >0 - eingestellte Baudrate
  156.   EUNDEV - Ungültiges Device
  157.  
  158.   Anmerkung: Durch die Rückgabe der nächst niedrigen verfügbaren Baudrate kann
  159.   der Aufrufer alle für dieses Device verfügbaren Baudraten durch "Abklappern"
  160.   von oben nach unten ermitteln.
  161.  
  162. -----------------------------------------------------------------------------------
  163. LONG XSOBaud(WORD device, LONG baudrate)
  164.   Ausgabe-Baudrate (genauer: bps) des angegebenen Devices setzen/abfragen. Die
  165.   Funktionsweise ist ansonsten analog zu XSIBaud.
  166.  
  167.   Die meisten Devices unterstützen keine getrennten Baudraten für Ein- und Aus-
  168.   gabe. In diesem Fall wird mit einem XSOBaud gleichzeitig auch die Eingabe-
  169.   Baudrate verändert (dies kann mit XSCapMap abgefragt werden).
  170.  
  171.   Rückgabewert:
  172.   >0 - eingestellte Baudrate
  173.   EUNDEV - Ungültiges Device
  174.  
  175. -----------------------------------------------------------------------------------
  176. WORD XSBreak(WORD device, WORD on)
  177.   Ein BREAK auf dem Device setzen/löschen. Wenn `on' ungleich 0 ist, wird BREAK
  178.   gesetzt, ansonsten gelöscht. Wenn das Device BRE